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Id, In With the Mew 



The Apple II had a tough time in the closing moments 
of 1989. Apple's pre-Christmas profits were far less 
than expected (with the rumorists and USA TODAY 
blaming the Apple II's slow sales!), and our beloved 
CALLA.P.P.L.E. expired. The next issue we receive 
will no doubt be the last. 

Before you all run out and buy a NeXT (ha!), stop and 
consider two things: 

First, I had an inkling about all this back in August. 
To wit, " . . Apple has yet to reap all the consequences 
of years of neglect and exploitation. Computer 
markets turn slowly nowadays, and Apple's moder- 
ate amount of support at present will not stem the 
tide in the short term." (Vol.1 No. 7, p. 3) 

Second, blame for the demise of CALL A.P.P.L.E., 
the only multi-language technical journal for the II, 
can be at least partly laid at the feet of Apple, Inc. 
Listen carefully, now, I am not denigrating those 
who work on and champion the Apple II at Apple, 
Inc. Those folks are doing a tremendous work. I am 
suggesting, however, that one of the unfortunate 
ramifications of Apple's decision to take APDAback 
in-house was that the move left Tech Alliance all 
dressed up with no place to go. The co-op had hired 
lots of employees and managers, made capital in- 
vestments in hardware and buildings, and had built 
APDA into a fairly well-established concern. With 
the rug pulled out from under them, they were left 
scrambling to cut costs as fast as possible. I can 
assure you that is harder to successfully pull off 
than expansion. 

My hunch is that, for whatever reasons (the rumor 
mill has churned out a hundred stories) the CALL 
A.P.P.L.E. folks couldn't make it happen in time to 
keep the magazine from financial disaster. 

In conclusion, friends, the passing of our beloved 
CALL A.P.P.L.E. is not really a commentary on the 
state of the Apple II market. It is the unfortunate 
symptom of a long chain of events. I don't know if 
Apple, Inc.'s decision to take back APDA was good or 
evil - but it had a nasty side effect. Though it be a 
grievous wind that hath blown in our faces this 
holiday season, there is yet reason for hope - Apple 
obviously does have plans for the II line, and my 
sources suggest some actual marketing money in 



the pipeline. 

As I've said before, I think there shall be rewards for 
those who persevere, but even now the worst is 
probably not over. 

On the positive side, one idea I've heard floated is for 
Apple to appoint an "Apple II Czar", i.e. someone to 
put the corporate infrastructure aright as far as the 
II is concerned. This has some potential, I think, 
especially since the stockholders really took a hit in 
the wallet the last few days. Stockholders don't care 
which product makes them bucks - as long as they 
are making their money. Bucks is bucks, after all. 

The subscriber survey... 

My thanks to all who took the time to return the 
subscriber survey. I really learned a lot. Here's how 
it turned out... 

As of this date (early December), 80 of you re- 
sponded. Not everyone answered every question, so 
the number of responses per question doesn't al- 
ways add up to 80. 

1) I find the content of the Apprentice: 

® 10 said too difficult 

• 12 said too simplistic 

• 53 said about right 

2) I find the tone of the newsletter: 

» 27 said too light, cut the chatter 

• 53 said about right 

3) I find the page layout in this issue: 

• said too squished 

• 43 said not enough content 

• 36 said okay, a decent tradeoff 

4) I find the current mix between 8 & 16 bit: 

• 17 said too biased in favor of the GS 

» 1 7 said too biased in favor of the 8 bit Apples 

• 45 said about right 

5) If Apple discontinues the Apple II, I would: 

• 28 said buy an IBM PC or compatible 
9 16 said buy a Macintosh 

• 33 said "other" 
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6) I use my Apple II... 

9 73 at home for word processing, etc. 
9 37 for business purposes 
9 35 for educational software 

7) Topics I'd like to see... 

Too numerous to even summarize - but I have lots 
more ideas now, thank you. We're addressing some 
of them this very month. 

8) If the subscription price were raised to $35 per 
year for 12 pages per month, I would: 

9 54 said continue subscribing 

• 22 said not renew 

Over half (44) attached extra pages or wrote on the 
back. I read every letter and note. 

• To all of you who asked how I can continue 
producing this newsletter if my margin is so small: 
I can afford to continue because A) I consider The 
Sourceror's Apprentice a long term investment, and 
B) I do a considerable amount of contract program- 
ming, consulting, and custom applications develop- 
ment. It was obvious, I hope, that SApp (as I call it) 
is not my main gig. As uncomfortable as this might 
make some of you feel, I recently co-authored a 
Macintosh product that is doing pretty well. I 
encourage you to delight in the ironic fact that, for 
once, something on the Macintosh is subsidizing 
something on the Apple II. I know I do. 

9 To those who wondered if I weren't "too nice" to be 
in business - now there is a criticism I can take! In 
actuality, I cannot figure out why business people in 
general are not the nicest human beings on the 
planet - after all, they're trying to persuade you to 
voluntarily give them your money. I, for one, don't 
do business with anyone who isn't trying very hard 
to keep me happy. As you'll see in a few paragraphs, 
the subscriber survey has convinced me that I have 
not been being nice enough! (Although it is a fact 
that surveys of this kind tend to get the most 
satisfied and the least satisfied to respond.) 

The way we were... 

I have not been able to offer nearly as much of my 
time to The Apprentice as I would have liked. Robert 
Muir (the letter I lead with last month) was right 
about that. That's part of the reason why the tone of 
this rag has been pretty informal and the distribu- 
tion schedule pretty loose. As I mentioned above, 
that's also why we've been able to continue when 
others have croaked. 

Still, I don't really think there is anyone in a better 
position to publish something of this nature (a 
conceit, perhaps, but we entrepreneurs have got to 



believe in ourselves) , and I also don't think it can be 
produced any cheaper. Everyone wants more for 
their money (see survey question #3!), but as I 
explained last month, it can't be done with our 
present structure. 

It is a foolish businessman, however, who doesn't 
listen to his customers. Well over half of you who 
responded want more for your money, and it now 
behooves me to figure out a way to make it happen. 

...and the way we shall be. 

• The bad news first: a small price increase. One 
year will now be $29.95, two years will $56. The 
quarterly disk will be $25 per year. 

In return, I am "professionalizing" this publication 
somewhat. I am hiring out the disk duplication 
duties so that they can be distributed in a more 
timely fashion, and I am negotiating with one per- 
son to be an associate editor and another high 
powered type to be a regular columnist. They are 
both good and would really help bump us up to the 
next notch in the publishing hierarchy. 

9 To offset their pay and to provide funds for an 
expanded format, I am going to aggressively pursue 
advertisers. With CALL A.P.P.L.E. out of the picture, 
we are now one the primary contact points with the 
Apple II programming community. If you have de- 
veloped something for programmers or have hard- 
ware for sale, please consider an ad here. 

Don't expect a glossy cover and four color ads. But 
we are most definitely going to do our level best to be 
responsive to your desires. Incidentally, our ad 
policy will not allow the sacrifice of editorial space 
for advertising space. My intention is to use the ad 
monies (when and if we can get them) to finance 
additional articles. 

CALL A.R.T.I.C.L.E.S 

Since we're going to be needing more quality code 
and articles than I and my cohorts could possibly 
generate, I am hereby requesting that the 12 of you 
who found this newsletter too simplistic start writ- 
ing for us (and contact your hotdog buddies, too). 
I've moved the pay up a notch, we're looking at $75 
- $125 for a nice piece that requires neither too 
much rewriting or recoding on my part. All submis- 
sions require articles in unformatted text files and 
source code in Merlin format. 

As for the other survey questions... I thought it 
hilarious that there was an exact tie betwixt those 
who want more GS stuff and those who don't. It's a 
no-win deal for an Apple II publisher. I've even 
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heard the boys at A2-Central moaning about this. 

I also found it interesting that our survey yielded 
only 16 of 80 who would move to the Mac if Apple 
ended the life of the II. You can bet that I'll be 
forwarding the results to Mr. Sculley. The "other" 
computer of choice was probably the Amiga. 

All in all, the survey results were most encouraging. 
My thanks to everyone, and especially to those who 
took the time to share their ideas, insights, and kind 
words. You Apple II foks are an intelligent, articu- 
late bunch, not to mention patient and kind (well, 
most of you, anyway). 

A GS BASIC 4U? 

Micol Systems, Canada, is up to version 3.5 of their 
GS BASIC. Up until now I've been fairly lukewarm 
about the product. It has some nice features, but 
Micol was making some decisions I really couldn't 
understand, including only supporting the linking 
of assembly files generated by their own assembler. 

You can guess how I felt about that, being one of the 
world's foremost Merlin promoters. 



After a long period of discussion, the Micol gang has 
finally come around to my way of thinking. We are 
currently E-MAILing each other silly trying to work 
out the details. I plan an article or series of articles 
on mixing Micol with Merlin. 

The Micol people are also planning some other very 
intelligent moves, so I am therefore finally offering 
the software for sale for $95 to subscribers (ship- 
ping not included). The suggested retail is $149.95. 

Incidentally, in a no-holds-barred effort to get back 
on our publishing schedule, this issue is a doubler, 
meaning it includes the material for both November 
and December. I know I had a lot of non-program- 
ming material to discuss, but at least it was two 
months worth! 

We aim to please, though, and if the idea of a "one 
fer two" bothers you, drop us postcard and we'll 
extend your subscription a month. 

I hope you had a blessed Christmas and I give you 
all my best wishes for a happy New Year - and New 
Decade, too. 

== Ross == 



Jumping Around, Hiring a Picker f & a P8 
MLI Error HaimcUer 

by Ross W. Lambert, Editor 

One of the most popular types of articles requested in the subscriber survey was that of pre-cooked and re- 
usable subroutines. It reminds me of my days as a teacher - whenver a specialist would come to "inservice" 
us poor schmucks, we'd invariably cry, "Gimme a worksheet!", meaning "Give me something I can use right 
now in my classroom." They seldom did, by the way. I'll try to respond better. 

In this month's listing, I have tried to give you a reusable ProDOS 8 MLI error handler that you can just link 
into your own code with very little modification. Not only that, but I have also attempted to illustrate a few 
techniques for selecting myriads of options that I have found useful. 

The first section of code begins by setting up the screen. I don't care if the screen is in 40 or 80 columns 
- the error messages all fit correctly either way. The Imprint subroutine called in line 37 was first run in the 
very first Apprentice (Vol. 1 No. 1, January, 1989). I made a minor modification for this article so I have 
reprinted it again. You can see it's usefulness in lines 38-41; the screen layout is done very much like you 
would in BASIC or another higher level language. 

The Imprint routine also makes use of a 65XXX series habit of depositing the return address after a JSR 
right on top of the stack. In this case Don Lancaster (the original author) bumped the return address by 
the length of the strings to be printed so that program control would resume immediately after the embedded 
ASCII text. It's a neat trick, I think. 



Although none of the routines in this program need parameters, a similar technique can allow us to pass 
data back and forth between generic routines (I'll detail this more next month) . This allows for incredibly 
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modular programming; which is in turn the secret to productivity. I can assure you that, for many 
employers, the speed with which you churn out a working application is sometimes of the highest 
importance. Please make a mental note, however, that in certain situations where blinding speed is 
required, a custom in-line routine can execute faster than a generic subroutine. 

Speaking of modularity, I have setup this program into three separate, independent, linkable modules. The 
demo module (Listing 1) is only useful to show off the other two, of course, but the embedded string printer 
and the MLI error handling module are ready to be linked into you own code as-is. Don't forget to declare 
their entry points as labels EXTemal to your source file. 

Meanwhile, back at the BRAnch (hehehe), the demo loop in lines 43 -62 merely grabs an MLI error code 
from a table and passes it to the error handler. The error handler looks for a match in its own table of error 
numbers, jumps to the appropriate routine, displays an error message and waits for a keypress. Try to not 
to get excited when the demo tells you your volume bitmap may be damaged; it's only a test of the system. 
If this were an actual emergency. . . 

Listing 1 - The Demo Module 

J ***>{<*>!<>^******>l<******>!<** *>!<***>!<>)< *****>)< >i<*>i<*>!<>!<>!<>!<>S<>l<>i<>)<>i<>!< 

2 * * 

3 * A General Purpose P8 MLI Error Handler * 

4 * By Ross U. Lambert * 

5 * * 

6 * Copyright (£D 1989 * 

7 * Ariel Publishing, Inc. * 

8 * All Rights Reserved * 

9 * * 

11 

12 

13 * Stuff for tlerl in 

14 

15 mx SI 1 

16 REL ; we're making linkable files 

17 DSK DemoModule.L 
18 

19 LST OFF 

20 

21 * A few equates 

22 

23 OurPtr = $06 ; zero page pointer 

24 

25 BELL = $FF3A 

26 HOME = $FC58 ; clear screen, home cursor 

27 ProDOS = $BF00 ;ProDOS MLI entry point 

28 COUT = $FDED 

29 CROUT = $FD8E ; generate a carriage return 

30 Keyboard = $C000 ; read a key 

31 ClrStrobe = $C010 ;clears keyboard queue 

32 PRHEX = $FDE3 ; pr i nt lower nibble of A as hex char 
33 

34 * Declare our external references... 

35 

36 EXT Impr i nt, error 1 i st, MLI_Error 

37 

38 * Real stuff starts here... 

39 

40 Start JSR Home 

41 JSR Imprint 

42 ASC "P8 MLI Error Trapper Demo",8D,8D 

43 ASC " Cycling through MLI errors ",8D 
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28 


STfl 


PTRSRVE+1 


29 
30 


PLfi 




31 


STfl 


OurPtr 


32 


PLR 




33 


STfl 


OurPtr+1 


34 






35 


LDX 


«0 


36 


STX 


HTflB 


37 


JSR 


CROUT 


38 


LDV 


«0 


39 






40 nxtchr2 


INC 


OurPtr 


41 


BNE 


nextchr 


42 


INC 


OurPtr+1 


43 






44 hextchr 


LDfl 


(OurPtr) , Y 


45 


BEQ 


ex i t4 


46 


JSR 


COUT 


47 


JMP 


nxtchr2 


48 






49 exit4 


LDfl 


OurPtr+1 


50 


PHfl 




51 


LDfl 


OurPtr 


52 


PHfl 




53 






54 


LDfl 


PTRSflVE+1 


55 


STfl 


OurPtr+1 


56 


LDfl 


PTRSflVE 


57 


STfl 


OurPtr 


58 


RTS 




59 






60 PTRSflVE 


DS 


2 



do likewise for $07 
:pu11 return address off stack 

: move cursor flush left 

: move down a 1 i ne from 1 ast cursor 

: i nc po i nter to po i nt at text 

:if it rolled, i nc highbyte, too 

: get character 

: term i nate on zero 



: get hi byte of return address 

: push back onto stack 

: get 1 obyte 

: and push back onto stack 

: restore zero page 



data table 



The error handling module itself does some peculiar things. Let's pick 'em apart. 

First, it scans the list of error numbers looking for a match. It increments the X register so that when a 
match is found it can use X as an offset into a jump table. The jump table that begins at line 89 (JMPFL) 
is a list of the addresses of our error handlers. There is an error handler for each error (although if you 
look at the handlers themselves several of them handle more than one error). 

When a match is found, the routine moves the X register into the accumulator, shifts left to double it, then 
moves it back into X. Since the addresses in the table at JMPFL are two bytes each, the offset needs to 
be doubled in this fashion to point us to the correct error handling routine. 

The final bit of weirdness is the manner in which I actually did the jump. Instead of moving the address 
to zero page and doing an indirect JMP (a buggy opcode on the 6502, by the way) it is faster to read each 
address directly and push it on the stack. Why the stack? Hmmm... well, it is a little bit of scullduggery, 
I must admit. We're going to fake out the CPU. If the address of the error handler is on top of the stack 
and we then execute an RTS, the CPU just returns control to the address sitting on top of the stack. Our 
silicon savant does not know whether we really JSR'd or not, and it doesn't care. The PHA highbyte, PHA 
lowbyte, and RTS combination is a quick and effective method for jumping who-knows-where. The lookup 
table of addresses combined with this technique makes for a very effective "option picker", as Don 
Lancaster called it in The Assembly Language Cookbook for the Apple II /lie. (Although the book is getting 
a little long in the tooth - it discusses EDASM in depth - it still is an invaluable resource for 8 bit 
programmers. I'm sure Don himself could put a copy in your hands. Call 602/428-4073). 

Speaking of the lookup table of addresses, you might notice that they all are the destination address less 
one byte. The reason for this is that the RTS returns control to the code living one byte past the address 
left on the stack. 



Listing 3 - The Error Handling Module 
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1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 



* * 

* Segment: Error Handler * 

mx 811 

REL 

DSK NLI.ERR.L 

LST OFF 

* fl few equates 

OurPtr = $06 

BELL = $FF3fl 

COUT = $FDED 

CROUT = $FD8E 

Keyboard = $C000 

ClrStrobe = $C010 

PRHEX = $FDE3 

* Our lone external reference 

EXT Imprint 

* The MLI and our demo module passes the 



: zero page pointer 



: generate a carriage return 

: read a key 

: clears keyboard queue 

; lower nibble of fl as hex char 



MLI_Error ENT 
STfl 
JSR 
LDfl 

LDX 
scan CMP 
BEQ 
DEX 
BNE 

BRK 

matchf ound 

TXfl 
flSL 
TAX 
LDF) 
PHfl 
LDfl 
PHfl 

RTS 



errorl i st ENT 



error_number 

BELL 

error_number 

»28 

errorl i st, X 

matchf ound 

scan 



error number in the accumulator 



store error number 



29 MLI errors 



JMPFL+1,X 
JMPFL.X 



DFB 


1 


DFB 


4 


DFB 


$25 


DFB 


$27 


DFB 


$28 


DFB 


$2B 


DFB 


$2E 


DFB 


$40 


DFB 


$42 


DFB 


$43 



should never get here 



: for doubl i ng 
:to use as offset 

: push page address onto stack 



a "fake* 1 - allows indirect jump! 



; L i st of MLI errors by number 
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66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 

81 

82 

83 

84 

85 

86 

87 

addr] 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 

100 

101 

102 

103 

104 

105 

106 

107 

108 

109 

110 

111 

112 

113 

114 

115 

116 

117 

118 

119 

120 

121 

122 

123 

124 

125 

126 

127 

128 



DFB 


$44 


DFB 


$45 


DFB 


$46 


DFB 


$47 


DFB 


$48 


DFB 


$49 


DFB 


$4fl 


DFB 


$4B 


DFB 


$4C 


DFB 


$4D 


DFB 


$4E 


DFB 


$50 


DFB 


$51 


DFB 


$52 


DFB 


$53 


DFB 


$54 


DFB 


$55 


DFB 


$56 


DFB 


$57 


DFB 


$58 



* table of error handler addresses Call -1 'cuz RTS takes you one PAST 



JMPFL 



Dfi 


errl-1 


Dfl 


err4-l 


DR 


err25-l 


Dfl 


err27-l 


DR 


err28-l 


DR 


err2B-l 


DR 


err2E-l 


Dfl 


err40-l 


Dfl 


err42-l 


Dfl 


err43-l 


Dfl 


err44-l 


Dfl 


err45-l 


Dfl 


err46-l 


Dfl 


err47-l 


Dfl 


err48-l 


Dfl 


err49-l 


Dfl 


err4A-l 


Dfl 


err4B-l 


Dfl 


err4C-l 


Dfl 


err4D-l 


Dfl 


err4E-l 


Dfl 


err50-l 


Dfl 


err51-l 


Dfl 


err52-l 


Dfl 


err53-l 


Dfl 


err55-l 


Dfl 


err56-l 


Dfl 


err57-l 


Dfl 


err58-l 



* Multiple labels for the same address here because MLI errors [in hex] 

* are not user-correctable. These ar& programmer's problems! 



errl 

err4 

err25 

err43 

err4fl 



invalid MLI command/programmer error 
invalid parameter count/prog . error 
interrupt table full 
; f i 1 e not open error 
incompatible version of ProDOS 
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129 err50 ;file busy error 

130 err55 ; VCB table full 

131 err56 ; buf f er in use 
132 

133 JSR Imprint 

134 flSC "Error »: ",00 

135 LDR error_number ; move high nibble down to low nibble 

136 LSR 

137 LSR 

138 LSR 

139 LSR 

140 JSR PRHEX 

141 LDfl error_number 

142 JSR PRHEX ; print low nibble 
143 

144 JMP DoPrompt 
145 

146 err27 JSR Imprint 

147 flSC "I/O ERROR", 8D, 00 

148 JMP DoPrompt 
149 

150 err28 JSR Imprint 

151 flSC "NO DEVICE CONNECTED", 8D 

152 RSC "Check slot and drive sel ect i on . ", 00 

153 JhP DoPrompt 
154 

155 err2B JSR Imprint 

156 RSC "Vour disk is write protected . ", 8D, 00 

157 JMP DoPrompt 
158 

159 err40 JSR Imprint ; invalid pathname syntax 

160 RSC "INVRLID PATHNAME", 00 

161 JMP DoPrompt 
162 

163 err45 ; two MLI errors related to not 

164 err2E ;having a volume online 

165 JSR Imprint 

166 ASC "VOLUME NOT ONLINE", 8D, 00 

167 JSR vol_prompt 

168 JMP DoPrompt 
169 

170 err42 JSR Imprint 

171 ASC "BUFFERS FULL", 8D, 00 

172 JMP DoPrompt 
173 

174 err44 JSR Imprint 

175 ASC "DIRECTORV NOT FOUND", 8D, 00 

176 JMP DoPrompt 
177 

178 err46 JSR Imprint 

179 ASC "FILE NOT FOUND", 8D, 00 

180 JMP DoPrompt 
181 

182 err47 JSR Imprint 

183 RSC "DUPLICATE FILE NAME", 8D, 00 

184 JMP DoPrompt 
185 

186 err48 JSR Imprint 

187 ASC "DISK FULL", 8D, 00 

188 JMP DoPrompt 
189 

190 err49 JSR Imprint 

191 ASC "DIRECTORV FULL", 8D, 00 

192 JMP DoPrompt 
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193 
134 
135 
136 
197 
138 
133 
200 
201 
202 
203 
204 
205 
206 
207 
208 
203 
210 
211 
212 
213 
214 
215 
216 
217 
218 
213 
220 
221 
222 
223 
224 
225 
226 
227 
228 
223 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
243 
250 
251 
252 
253 
254 
255 
256 



err4B JSR 
flSC 
JMP 

err4C JSR 
RSC 
JMP 

err4D JSR 
RSC 

JMP 

err4E JSR 
RSC 
JMP 

err51 JSR 
flSC 

JMP 

err52 JSR 
RSC 
JMP 

err53 JSR 
flSC 
JMP 

err57 JSR 
RSC 
JMP 

err58 JSR 
RSC 
JMP 



get_response 
JSR 
LDR 
JSR 
STR 

rdkbd LDR 
BPL 
CMP 
BEQ 
CMP 
BNE 



exit3 



DoPrompt 



JSR 
RTS 



JSR 
RSC 
RSC 
JSR 
RTS 



Imprint 

"FILETYPE ERROR", 8D, 00 

DoPrompt 

Impr int 

"OUT OF DRTR",8D,00 

DoPrompt 

Impr i nt 

"RANGE ERROR", 8D, 00 

DoPrompt 

Impr int 

"FILE LOCKED", 8D, 00 

DoPrompt 

Impr i nt 

"THE DIRECTORY MAY BE DAMAGED", 8D, 00 

DoPrompt 

Impr i nt 

"NOT A PRODOS DISK", 8D, 00 

DoPrompt 

Impr i nt 

"INVALID PARAMETER", 8D, 00 

DoPrompt 

Impr i nt 

"DUPLICATE VOLUMES ONLINE", 8D, 00 

DoPrompt 

Impr i nt 

"The volume bitmap may be damaged !", 8D, 00 

DoPrompt 



CROUT 

«"_" 

COUT 

ClrStrobe 

Keyboard 

rdkbd 

«$8D 

exi t3 

«155 

rdkbd 

CROUT 



; pr i nt cursor 

; RETURN? 
; escape? 



vol _prompt 

JSR 



Impr i nt 

"Press RETURN to try again,",8D 

"ESCape to abort. . . ",00 

get_response 



Imprint 
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257 flSC "Please insert: ",80,00 

258 

259 * This section requires a volume name (which is potentially kept in various 

260 * places). For this demo I've hardcoded a fake path at Pathname. Depending 

261 * on your application, you might want to do a GET_PREFIX and display that. 
262 

; put location of path into zero page 



; 1 ength of str ing 

; of f set to skip length byte 

;clean up display 



263 




LDfl 


»<Pathname 


264 




STR 


OurPtr 


265 




LDfl 


«>Pathname 


266 




STfl 


OurPtr+1 


267 








268 




LDX 


Pathname 


269 




LDV 


»1 


270 


: 1 OOp 


LDfl 


COurPtr] ,V 


271 




ORfl 


8$80 


272 




JSR 


COUT 


273 




INV 




274 




DEX 




275 




BEQ 


h i story 


276 




JMP 


: 1 oop 


277 








278 


h i story 


JSR 


CROUT 


279 




RTS 




280 








281 


error_number 


DFB 


282 








283 


Pathname 


STR 


"/THIS. IS. A. TEST" 



Listing 4 - Linker Names File Creator (Merlin 8 only) 

2 * * 

3 * Names File Creator for Merlin 8 Linker * 

4 * * 

6 
7 

8 DSK ML I .NAMES 

9 STR "DemoModule.L" 

10 STR "Embedstr.prtr.L" 

11 STR "MLI.ERR.L" 

12 BRK 

Listing 5 - Linker Command File (Merlin 16 only) 

l 

2 >)<*>^*>|<H<*>KH<>!<>^^>^*>!<*>!<**>(<>^>^>(<>!<>^>f<>!<>!<>S<>!<*>l<>!<>i<*>!<>!<>i<>!<>l < **>!<>(< **>(< + + >)< 

3 * * 

4 * Linker Command File for P8 MLI Error Routines * 

5 * CMerl in 16 only) * 
5 * * 

7 *^>|<*>j<>!<^>|<>^>!<*>{<>^>|<)}<>^*)|<>|<>!<>j<>j<>^*>^>^>^*>^>H>j<*>^>!<*>^>H*>i<>i<*>l<****^*** 

8 

$2000 ; let's create a SVS file 

$FF 

$00 ; specify absolute linker [P8] 

ml i .err . 1 ink.s ; change to your names for each 

str . pr i nter . s ; i f you rename them ! 

ml i .err .demol . s 



3 


org 


10 


typ 


11 




12 


lkv 


13 




14 


asm 


15 


asm 


16 


asm 


17 
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18 


Ink 


demomodul e . 1 


19 


Ink 


embedstr .prtr . 1 


20 


Ink 


ml i . err . 1 


21 






22 


sav 


ML I. ERR. DEMO 



I had Merlin 8/16 and then got the update to Merlin 1 6+. The additional documentation I received 
did not point out that you could link 8 bit files with no hassle using the 16+ linker. Through a 
little experimentation, I discovered that the LKV $00 pseudo op still invokes the absolute linker, 
so your eight bit code links like a charm even in Merlin 16+. And at the risk of provoking the ire 
of all you He and lie fans, I am compelled to add that the IIGS and Merlin 16+ is an absolutely 
incredible 8 bit programming environment. The command files of the linker are flexible, powerful, 
and easy to use, and the linker itself is like lightning. All of the files in this program linked and 
saved to disk in 3 seconds to my Applied Ingenuity Inner Drive. 

For some perverse reason it is tempting, when starting a new project, to write the entire thing 
from scratch. Hopefully our example of re-usable, linkable files will help at least some of you to 
discover the speed and power inherent within a more modular style. 

== Ross == 



Magic Text : Using USR 

More Merlin Magic 
From Jerry K 

By Jerry Kindall, Contributing Editor 

MagicText is a USR function for Merlin 8/16. It was 
designed for maximum flexibility in entering TXT 
strings. In fact, MagicText can replace all of Merlin's 
text opcodes, except for STR (and that's only be- 
cause I couldn't fit the code to handle a leading 
length byte into page 3 of RAM). 

To install MagicText, you simply press D (for Disk 
Command) at Merlin's main menu , then type BRUN 
MAGICTEXT. Once you've done that, MagicText will 
be installed and ready to use. (You can also auto- 
matically run MagicText when you run Merlin by 
putting its pathname into Merlin's startup buffer, 
but then Merlin wouldn't load the full screen editor 
automatically.) 

Using MagicText 

MagicText is activated by a USR psuedo-op in your 
sourcecode. (If you use Merlin 16, use USRO instead 
of USR.) A typical MagicText statement might look 
like this: 



greeting usr 'Hi there!' ; greet ing str i ng 

That's a simplistic example, of course, and it doesn't 
show you the flexibility of MagicText at all. However, 
notice that, just as with any other Merlin psuedo-op, 
you have an optional label, the opcode, the operand, 
and an optional comment. 

MagicText will allow you to use any character at all 
(except the tilde character, ~) as a delimiter for the 
string, but I suggest the use of the apostrophe or 
quote. With MagicText, there's no reason to ever 
need more than one delimiter. 

MagicText works its magic by means of the tilde 
character. The tilde has special meaning in Mag- 
icText strings. For example, if you put ~A in a 
MagicText string, MagicText will insert a control-A 
character into the string. (In fact, any character in 
the ASCII range 64-95, which includes the upper- 
case letters and the symbols @, [, \, ], A , and _, will 
generate a control character when preceded by a 
tilde.) 

Here's an example, which contains two bell charac- 
ters embedded in the text: 



usr ""QFlre you auuake?~G" 



; awaken user 



If you follow the tilde with another tilde, MagicText 
will put one tilde character into the object code. If 
you follow the tilde with a quote mark or an apostro- 
phe, MagicText will insert those characters as well, 
even if you're using one of them as a delimiter. 
Here's an example: 
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usr "Joe said, ""l am going to the store. *"" 

If you follow the tilde with a dollar sign, MagicText 
will interpret the two characters after the dollar sign 
as a hex byte. Here's an example of using this 
feature to terminate a string with a carriage return 
and a zero byte: 



usr "Main menu 

selection~$8D~$00" 



Please make 



MagicText also recognizes a few lower-case letters 
after the tilde, as flags to change modes. Remember, 
if you use upper-case letters, MagicText will con- 
sider the letter a control-character. (Note: ~1 is a 
lower-case letter L, not the numeral one.) 



Switch to low-ASCII [high bit clr] chars 

Switch to hi -ASCI I Ch i gh bit set] chars 

Switch to inverse text 

Switch to flashing text 

Switch to MouseText 

Switch back to normal text [high-ASCII] 



MagicText uses the ~1 and ~h Hags to select high or 
low ASCII text, instead of looking at the delimiter. 
Text is always assumed high ASCII unless you use 
the ~1 flag to specify low ASCII. (MagicText passes all 
characters except hex bytes through the high /low 
ASCII flag, including control characters and the 
bytes generaled by ~~, -', and -".) 

The ~i, ~f, and ~m flags cause MagicText to manipu- 
late the ASCII codes of your text to produce the 
desired types of characters. Inverse text works 
properly in 80-column mode, with both upper and 
lower case (in 40-column mode, lower case inverse 
text is displayed as flashing punctuation and nu- 
merals). Flashing text does not support lower-case. 
MouseText expects you to specify an ASCII code in 
the range of 64-95 (the letters and symbols @, [, \, 
], A , and J. 

The display flags ~i, ~f, and ~m are useful mostly for 
applications that will be storing characters directly 
to screen memory, or using only the 40-column 
output routines. The 80-column firmware will ig- 
nore some of these ASCII codes or treat them as 
control characters (in particular, the uppercase 
inverse letters) . 

The ~n flag is actually the same as ~h and sets high- 
ASCII normal characters. The ~1 flag will also turn 
off ~i, ~f, or ~m, and switch to low-ASCII characters. 
Here's an example which generates the ASCII codes 
for a small mousetext box: 



usr ""mZ\\\\ A " 
Here's another example with an inversed word: 



usr 



'It's time to" i PARTV "n" 



How Does It Work? 

If you're not familiar with Merlin's USR opcode, you 
should check out pages 124 and 125 in the Merlin 
8/16 manual. (That information probably moved 
around somewhat when Merlin 16+ was released. 
Check the index if you don't find it on pages 124- 
125. 

MagicText starts out by hooking itself up to Merlin's 
USR vector (lines 80-90) . Notice that the code which 
does this actually resides in the input buffer, but 
since that code won't be needed again, it's OK to put 
it in such an unstable memory location. The actual 
USR routine starts at address $300. 

The first thing MagicText does when it gets control 
is determine the delimiter being used and to initial- 
ize a few flags (lines 92- 103). Then it falls into the 
main processing loop (lines 105-135), which proc- 
esses each character in the operand. If a tilde is 
found, the tilde routine (lines 159-187) gets control, 
and examines the character after the tilde to figure 
out what to do. If a tilde is not found, the current 
mode (lo/hi ASCII, inverse/flash/mousetext) is 
checked and the character is adjusted accordingly 
before being placed into the object code. 

The tilde routine checks for ~, ', and " characters, 
and if it finds them following a tilde, places them into 
the object code via PROC (line 1 12). Next it checks 
for h, 1, i, f, m, and n; if they are found, the 
appropriate mode is set. If a dollar sign is found, the 
hex byte routine is activated. If none of these 
characters are found, the character is converted to 
a control character and put into the object code 
(lines 183-186). 

The hex byte routine (192-200) calls the hex digit 
routine (206-219) twice, once for each nibble, then 
combines the two nibbles into a byte and puts them 
into the object code. 

The code is a little bit tricky in places because of my 
desire to fit it into page 3 of RAM, but is otherwise 
fairly straightforward. It's a good example of how to 
write a USR routine for Merlin. 
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I've found MagicText quite useful in my programming. I hope you find it useful in yours. Enjoy! 



Listing 1 :MagicText Assembly Listing 



l 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 * 

16 * 

17 * 

18 * 

19 * 

20 * 

21 * 

22 * 

23 * 
24 
25 
25 

27 * 

28 * 
29 
30 
31 
32 
33 

34 * 

35 * 

36 * 

37 * 

38 * 

39 * 

40 * 

42 * 

43 * 



* 

* 
* 
* 
>« 
* 
* 



* 
* 
* 
* 
* 
* 
* 
* 



Mag i cText 

R Merlin 8/16 USR Routine 

by Jerry E . K i ndal 1 

August 1989 

Pub! i c Domain 



MagicText is a replacement for all of Merlin's 
various text-generation psuedo-ops . It allows 
you to switch between high ASCII, low ASCII, 
inverse, normal, flashing, and mousetext, and 
to insert control characters and hex bytes, 
all in the same source statement. The only 
thing that Mag i cText_can 't do is produce a 
1 ead i ng 1 ength byte you '11 still have to use 
STR for that. 



Syntax : 
USR 'text' 



comment 



The apostrophe is a delimiter and can be any 
character except " , and it must be matched 
by another such character. Apostrophe or quote 
recommended. An optional comment may follow. 

If a tilde C) is encountered in the text, the 
tilde and the character that follows it are 
treated specially. The following characters 
are valid after a t i 1 de (all letters MUST be 
1 ower case) : 



44 
45 
46 
47 
48 
49 

50 *$ 

51 *" 
52.* 

53 * 

54 * 
55 
56 
57 
58 



h: switch to high-ASCII characters 

n: switch to normal [high-ASCII) characters 

i: switch to inverse characters 

f: switch to flashing characters 

m : sw i tch to mousetext characters 

insert a tilde (ie, ~~ = one tilde) 

insert an apostrophe [ie, ~ ' 

insert a quote (ie, ~ " gives 
the next two characters are a 
$0D inserts the hex value 0D 



= one apost) 
one quote) 
hex byte; 



Any other characters are considered control 
chars: "A inserts a control -A, etc 



org 



$2F0 
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02F0 
02F2 
02F5 
02F7 
02FA 
02FC 
02FF 



0300 
0302 
0304 
0306 
0309 
030B 



030D 
0310 
0312 
0314 
0316 
0318 
031R 
031C 
031E 
0320 
0322 
0324 
0326 
0328 
032A 



R9 4C 
8D DA B6 
FI9 00 
8D DB B6 
A9 03 
8D DC B6 
60 



AS 80 
85 61 
85 60 
20 B9 03 
F0 38 
85 60 



20 B9 03 
F0 31 
C9 7E 
F0 41 
R6 61 
F0 23 
30 19 
E0 02 
90 19 
F0 06 
29 3F 
09 40 
D0 15 
C9 40 
90 11 



59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 



* Internal Merlin Entry Points: 

* See Merlin 8/16 Manual, pp 124-125 



opndlen = $BB ; 1 ength of operand 

uiorksp = $280 ; operand work buffer 

usrvect = $B6Dfl ;USR routine vector 

putbyte = $E5F6 ; put a byte into object 



Zero page locations used by this routine: 
Allocated by Merlin as temporary storage 



dl i mi t 

mode 

hold 



= $60 
= $61 
= $62 



; str i ng del i mi ter 

; ASCI I mode 

; temporary storage 



* Connect the USR routine to Merlin 



setup 



Ida 
sta 
Ida 
sta 
Ida 
sta 
rts 



«$4C 

usrvect 

»usrop 

usrvect+1 

«/usrop 

usrvect+2 



* USR psuedo-op entry po i nt 
* 

* On entry from Merl in: A = 0, V = 0, carry = 1 



usrop 



Ida 


«$80 


sta 


mode 


sta 


dl i m i t 


jsr 


get 


beq 


done 


sta 


dl i m i t 



;high ASCI I [normal ] mode 
; no real del i mi ter 
;get f irstchar of opernd 
;uie're at end of line 
;we have the delimiter 



* Main 



1 oop 



proc 



fls 



inv 



xt p 


rocess i 


Jsr 


get 


beq 


done 


cmp 


#'" ' 


beq 


ti lde 


ldx 


mode 


beq 


lo 


bm i 


hi 


cpx 


»2 


bit 


mst 


beq 


i nv 


and 


#$3F 


ora 


«$40 


bne 


lo 


cmp 


«$40 


bit 


lo 



ng 1 oop 



; get next char of operand 

: at end, we're done 

;is it a command? 

;yes, go do it 

ituhat mode we in? 

; low ASCII mode 

ihigh ASCII mode 

: 1 = mousetext mode 
;2 = inverse mode 
:else flashing mode 

:put the character 

:less than 64, OK already 
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032C 
032E 
0330 
0332 
0335 
0337 
0339 
033B 
033D 
0340 



0350 
0352 
0354 



0357 
035A 
035C 
035E 
0350 
0352 
0364 
0366 
0369 
036B 
036D 
036F 
0371 
0373 
0375 
0377 
0379 
037B 
037D 
037F 
0381 
0383 
0385 
0387 
0389 
038B 
038D 



C9 60 
B0 0D 
29 3F 
4C 3D 03 
09 80 
D0 04 
29 3F 
09 40 
20 F6 E5 
4C 0D 03 



0343: 60 



0344: A9 03 

0346: 2C 

0347: A9 80 

0349: 2C 

034A: A9 00 

034C: 2C 

034D: A9 01 

034F: 2C 



09 02 
85 61 
4C 0D 03 



20 B9 03 
C9 7E 
F0 B8 
C9 27 
F0 B4 
C9 22 
F0 B0 
20 BD 03 
F0 D8 
C9 24 
F0 20 
C9 68 
F0 D4 
C9 6C 
F0 D3 
C9 69 
F0 D5 
C9 6E 
F0 C8 
C9 6D 
F0 CA 
C9 66 
F0 BD 
29 IF 
A6 61 
F0 B0 
D0 A6 



123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 



hi 

mst 

lo 

done 



cmp 


»$60 


bge 


lo 


and 


•S00111111 , 


jmp 


lo 


ora 


»;?10000000 , 


bne 


lo 


and 


8^00111111 , 


ora 


«;?01000000 , 


jsr 


putbyte 


jmp 


1 oop 



greater than 96, it's OK 



convert to 0-32 
and put the char 
set hi bit of char 
and put i t 
convert to 0-32 . . . 
convert to 64-95 
put the character 
and go back to the 



top 



rts 



: we 're al 1 done ! 



* Set the var i ous text modes 



setfls 
seth i 
setl o 
setmst 
set i nv 



Ida 
hex 

Ida 
hex 

Ida 
hex 

Ida 
hex 

Ida 
sta 
jmp 



«$03 
2C 

«$80 
2C 

»$00 
2C 

«$01 
2C 

«$02 
mode 
1 oop 



* Handle tilde commands 



ti Ide 



jsr 
cmp 
beq 
cmp 
beq 
cmp 
beq 
jsr 
beq 
cmp 
beq 
cmp 
beq 
cmp 
beq 
cmp 
beq 
cmp 
beq 
cmp 
beq 
cmp 
beq 
and 
ldx 
beq 
bne 



;mode = 3 [flash] 

; f ake BIT to skip next i nstr 

;mode = $80 [norm/hi] 

;mode = (lo ASCII] 

; mode = 1 (mousetext] 



; mode = 2 [inverse] 
set it 
:back to the top 



get 

» '~ ' 

proc 

«$27 

proc 

#"" 

proc 

check 

done 

»'$' 

hex 

tt'h' 

seth i 

«' 1 ' 

setl o 

»' i ' 

set i nv 

«'n' 

seth i 

tt'm' 

setmst 

* 'f ' 

setfls 

*S00011111 

mode 

lo 

hi 



get char after tilde 
it's a tilde, do it 

it's an apost, do it 

quote, do it 

is it a del i m i ter? 
it is, exi t 
; $ = hex mode 

set high ASCII 

;set lo ASCII 

; set i nverse 

set normal [h i gh] 

set mousetext 

set flashing 

it's a ctrl -char 

if low ASCII on, set 1 oui 
; otherwise, set high 
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187 


















188 


















189 


















190 


* Handle hex 


bytes. 












191 










038F 


20 


A0 


03 


192 


hex 


jsr 


d i g 


;get one hex digit 


0392 


0A 






193 




asl 




;mul t by 16 


0393 


0A 






194 




asl 






0394 


0fl 






195 




asl 






0395 


0A 






196 




asl 






0396 


85 


62 




197 




sta 


hold 


;hold it 


0398 


20 


A0 


03 


198 




jsr 


d i g 


;get next digit 


039B 


05 


62 




199 




ora 


hold 


; combine with hold 


039D 


4C 


3D 


03 


200 
201 
202 
203 




jmp 


lo 


; and store it 










204 


* Get 


a hex c 


i g i t from o 


Derand 










205 










03fl0 


20 


B9 


03 


206 


d i g 


jsr 


get 


; get a char 


03A3 


D0 


04 




207 




bne 


val i d 


; it's F10K 


03A5 


88 






208 




dey 




; at EOL, return 


03FI6 


A9 


00 




209 




Ida 


«0 




03A8 


50 






210 




rts 




; back 


03A9 


C9 


60 




211 


val i d 


cmp 


«$60 


; 1 omer case? 


03AB 


90 


02 




212 




bit 


conv 


; no 


03AD 


E9 


20 




213 




sbc 


«$20 


;yes, fix to upper 


03AF 


38 






214 


conv 


sec 




; convert ASCII to hex 


03B0 


E9 


30 




215 




sbc 


tt '0' 




03B2 


C9 


0A 




216 




cmp 


«10 


; i t 's a number 


03B4 


90 


02 




217 




bit 


back 




03B6 


E9 


07 




218 




sbc 


«7 


;must be a letter; fix i 


03B8 


60 






219 
220 
221 
222 


back 


rts 




, 










223 


* Get 


one character from 


operand 










224 










03B9 


B9 


80 


02 


225 


get 


Ida 


morksp, y 


; get char from workspace 


03BC 


C8 






226 




i ny 




; and po i nt to next 


03BD 


C5 


60 




227 


check 


cmp 


dl i m i t 


; h i t del i m i ter? 


03BF 


F0 


02 




228 




beq 


rts 


; yep 


03C1 


C4 


BB 




229 




cpy 


opndl en 


; at end of 1 i ne? 


03C3 


60 






230 


rts 


rts 








Jl C? JiL 1L JlL#iJiLJI m 



By Jay Jennings 



Probably the most exciting new tool included with 
System Disk 5.0 is the TextEdit toolset. The old 
LineEdit toolset allows a user to enter and edit a 
single line of text in a program. TextEdit allows the 
user to enter multiple lines. In fact, TextEdit can be 
thought of as a full featured word processor. By full 
featured, I mean it supports multiple fonts, styles, 
and colors in the text, full editing according to the 
Human Interface Guidelines, and can support a 
document of virtually unlimited size... all this with 



one toolset! 

The purpose of this article is to show you how to 
create a little text editor with just a few lines of code. 
We won't go into different fonts, styles, and colors, 
however. That would take more pages than Ross will 
let me have. But we will include the load and most 
of the save code. 

Our program starts all needed tools, allocates a 64K 
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buffer for our text, creates a window, installs a 
TextEdit control, and then heads for the Event loop. 
There's no menu bar in this program. To quit the 
program, click on the close box of the window. 

The program currently doesn't save the text. You 
could do that by adding the TEGetText call (ex- 
plained in the article) and then writing the data to 
disk. This program also lacks any error checking. I 
left that out because of space, but you should check 
for errors after every tool call. 

Let's skip the descriptions of the normal stuff like 
opening windows and go straight for the throat of the 
TextEdit control. Then we'll back up and see how to 
install it in a window using NewControl2. 

The first parameter in the template is a parameter 
count. You can have as few as 7 parameters in the 
template or as many as 23. This depends on how 
many of Apple's defaults you want to accept . For our 
purposes, all we need are 18 parameters. 

dm 18 

The second parameter is the ID of our control. This 
needs to be unique for the window in which the 
TextEdit control resides. Just pick your favorite 
number. Notice that in the next line I use the "dl" 
pseudo-op. This is a macro that takes the place of 
the "adrl" pseudo-op just because define long makes 
more sense when defining a long number than adrl 
does. Right? (Editor: I think so. I've always felt funny 
using ADRL - ADdRess Long- when defining flags or 
other non-address sorts of things.) 



dl 



Parameter number three is four word values that 
specify the boundary rectangle for the TextEdit 
control. 

duj 5,5,170,610 

The fourth parameter is the actual value that indi- 
cates you're implementing a TextEdit control. 

dl $85000000 

The next two parameters are flags that specify how 
the TextEdit control will act while being used. The 
first of the two flag words must be set to zero. The 
second is a little more flexible, but 9 times out of 10 
you'll need to set it exactly as I show it here. 



Parameter number seven is a long space that is left 
blank. It's for our use so we can put anything we 
want in there. Well, anything that's not over four 
bytes long, anyway. 

Now we get. to the "grand- daddy" parameter... 
number eight. There are a zillion bits that mean a 
zillion different things (give or take a few). I'm just 
going to go through a few of the more important 
ones. Those I don't mention, just leave them as is 
until you latch onto the docs for the TextEdit toolset 
in the Apple IIGS Toolbox Reference, volume 3.4. 
(Editor: or until a future SApp article) 



ap the text 

t CR only 

ng permitted 

al or autoscrol 1 i ng 
permi tted 

i ng all owed 

erted i n document 

ext cntrl in window 
around TE control 
around TE control 

n select text 

nnot select text 



Here's the way the parameter looks for a "generic" 
kind of TextEdit control... 



B 


t 


28 



1 


= word wr 
= break a 


B 


t 


27 



1 


= scrol 1 i 
= no manu 


B 


t 


26 



1 


= ed i t i ng 
= no edit 


B 


t 


24 



1 


= tab i ns 
=tab to n 


B 


t 


23 




1 = 


= no rect 
=draw rect 


B 


t 


20 



1 


= user ca 
= user ca 



dl 80110. 
0000 



1010 1010 0000 0000 0000 0000 



Parameter number nine (actually four words) de- 
scribes the amount of white space to leave between 
the boundary rectangle and the text itself. The 
default values of 2, 6, 2, and 4 (top, left, bottom, 
right) can be specified by using $FFFF for each 
parameter. 

dw $FFFF,$FFFF,$FFFF,$FFFF 

Parameters ten and eleven concern the vertical 
scroll bar. Set them both to zero if you don't want a 
vertical scroll bar. If you'd like a scroll bar without 
any hassles, set parameter ten to $FFFF (or - 1) and 
parameter eleven to zero. This will give you a scroll 
bar that scrolls 9 pixels at a time. 



dl 
dw 



$FFFF 




dw 
dw 




80111 



0100 0000 0000 



The horizontal scroll bar is handled by parameters 
twelve and thirteen and are dealt with just like the 
vertical scroll bar was. Well, they will be, but hori- 
zontal scrolling isn't implimented yet. For now, they 
MUST be set to zero or bad things will happen to you 
and your computer. 
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dl 
dm 



The next four parameters (fourteen through seven- 
teen) are complicated enough that you'll need the 
manual to make good use of them. Just leave them 
as they are for the purposes of our demo code. 



;ref to style information 
; textDescr i ptor 
;ref to initial text 
; length of initial text 



The last parameter we'll deal with sets the maximum 
number of characters that we want our control to 
allow. Since our program sets up a 64K buffer for 
text, we'll specify that as the maximum size. 



dl 





duj 





dl 





dl 






dl 



65535 



Phew! The TextEdit template is done. Now we'll dive 
into the other two calls that are used with TextEdit 
quite a lot. The first, TESetText, grabs text from a 
buffer in memory and places it into the TextEdit 
document. The other, TEGetText, grabs the text 
from the TextEdit record and places it in a buffer. 
Then you'd be ready to save it to disk, transmit it 
over the modem, or whatever else you desired. 

There are six parameters that need to be pushed on 
the stack for TESetText. The first defines the format 
of the next parameter. Bits 3-4 show the next 
parameter is a pointer. Bits 0-2 specify that we're 
after an unformatted block of text. We're going to 
take the easy way out and use all pointers in our 
example (we could use handles or resource IDs if we 
wanted to get sneaky). That means the second 
parameter is a poinler to the text that will be inserted 
in the TextEdit document. The third parameter 
specifies the number of characters in the text buffer. 
The next two parameters should be set to zero as 
they're for style information and we won't be getting 
into that at this time. The last parameter is the 
handle to the TERecord in memory. But, we don't 
even have to worry about that too much because if 
we put a zero in that parameter it will default to the 
active record. Here's what the parameter list looks 
like for our program. . . 

PushUord »g00101 ; textDescr i ptor 

PushLong TextBuffer ; textRef 

PushLong TextLength ; textLength 

PushWord «0 ; sty 1 eDescr i ptor 



PushLong »0 

PushLong «0 

TESetText 



; styl eRef 
; teHandl e 
; make the cal 1 



The format for TEGetText is very similar. Since the 
call is going to return a result, we have to push space 
on the stack first. And instead of pointing to a block 
of text in memory, we point to a block of space that 
the text will end up in after the call. 

PushLong 80 ; space for result 

PushWord «^00101 ; buff erDescr i ptor 
PushLong TextBuf f er ; buf f erRef 
PushLong »65535 ; buf f erLength 
PushUord »0 ; styl eDescr i ptor 

PushLong «0 ; styl eRef 

PushLong «0 ; teHandl e 

_TEGetText ; yank out data 

PullLong Total Length ; 1 ngth of all 
text i n record 

In order for the TextEdit control to become active it 
has to be installed in our window. We use the 
NewControl2 call and install it just like any other 
control, like a button, checkbox, or edit line. The use 
(and abuse) of NewControl2 is a subject for the 
future, so for now, just stare very hard at that part 
of the source code and absorb the subtle intricacies 
through osmosis. Okay, I'll explain the parameters 
here very briefly. 

You push a long space on the stack first. The call 
returns a handle to the control although we don't do 
anything with that value in our program. 

The second parameter is the pointer to the window 
you want to install the control in. That value is the 
one returned in the NewWindow call made earlier. 

The third parameter is a reference for the fourth, and 
last parameter. By pushing a zero we're saying that 
the next parameter is a pointer to the template of a 
single control. By using different values for the third 
parameter we can specify that the last parameter 
will be a handle, pointer, or resource ID of a single 
template or table of templates. NewControl2 is avery 
handy call. It's made window -type programming 
very quick and easy (until you get to line edit 
controls... which is a subject for a future article). 
Here's what the NewControl2 call should look like... 

PushLong »0 ; space for result 

PushLong Wi ndoiuPtr; ptr uindui cntrl 
PushWord «0 ; ref descriptor 

PushLong«Templ ate; addrof cntrl tmpl ate 
_NewControl 2 
PullLong TEHandle ; retr i eve cntrl hndl 

That's it! You know everything needed to become a 
TextEdit guru . Well, you know enough to get started 
on it, anyway. Look over the source code and follow 
the logic to see what's happening. 
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Editor. You'll notice that Jay does aJSR Startup and 
JSR Shutdown - those are calls to routines virtually 
identical to the Generic Start II we ran last time. They 
can (and probably should) be put into reusable, 
linkable files. The only time they'd need to be 
changed is when your current application needs 
more tools than are included in those generic rou- 
tines. 

Incidentally, we had two reports of difficulties with 



Generic Start II, but had no luck tracking down the 
bug. We did find that the tools requested did not 
equal the tools listed in the StartStopRec, but that 
was not actually a fatal error. Jay and I both are 
using his code with no trouble, and the other person 
I sent a copy to has reported no problems either. 

That doesn't mean that anyone is crazy, of course, it 
just means that we couldn't replicate the problem (no 
response from TaslcMaster) . 



1 1st off 

2 *============================================================= 

3 * Mini word processor for The Sourceror's Apprentice 

4 * Another Mohawk Man Creation 

5 * Copyright 1989 - PunkUare 

6 *============================================================= 

7 xc 

8 xc 

9 mx %m 

10 cas in 

11 rel 

12 use mwp.macs 

13 put 1/tool , equates/el6 . ui i ndow 

14 put 1/tool . equates/el6 . memory 

15 put 1/tool . equates/el6 . gsos 

1 6 * 

17 do 

18 dl mac ; a new macro 

19 adrl ]1 

20 eom 

21 fin 

22 * 

23 phk 

24 plb ; set data and program bank the same 

25 jsr Startup ;load and start the tools 

26 jsr MemAlloc ; grab a 64K chunk for data 

27 jsr MakeU i ndow ;a window for TextEdit to live in 

28 jsr UakeTextEd i t ; . . . and make it active 

29 jsr GetFile ; choose a file to load 

30 bcs : NoF i 1 e ;if cancel was clicked, branch 

31 jsr SetText ; put the text in the window 

32 :NoFile 

33 _InitCursor 

34 jsr EventLoop ; go do that loop thing 

35 jmp ShutDown ; and exit the program 

36 * 

37 GetFi le 

38 ~SFGetFile2 «120; #40; »0; «Promptl ; *0; »0; »Repl yRec 

39 Ida ReplyRec ; see what was cl i eked 

40 bne .-Load ; if file picked, go load it 

41 sec 

42 rts 

43 :Load 

44 iGSOS _Open ; OpenParms; 1 
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45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
96 
97 
98 
99 
100 
101 



] 1 oop 



Ida OpenRefNum 
sta ReadRefNum 
sta CI oseRefNum 
MoveLong OpenEOF; ReadRequest 
MoveLong BufferPo i titer; ReadBuf f er 
iGSOS _Read;ReadParms ; 1 
iQSOS _Close;CloseParms; 1 
MoveLong BufferPo i nter; 50 
Idy OpenEOF 
$20 

y 



: move the 1 ength of file 
;move the buffer address 



sep 
Ida 
and 
sta 

dey 
bpl 
rep 
cl c 
rts 



[50], 
«$7F 
[50] , i 

] 1 oop 
$20 



move address to d i rect page 
get length of file if < 64K 
go to 8 bit accumulator 
grab a character 
strip off the h i ght bit 
and resave it 
; point to the previous character 
;if not -1, keep looping 
;back to 16 bit accumulator 



SetText 



"TESetText »8101 ; BufferPo i nter; OpenEOF; »0; »0; 
rts 



«0 



Startup 



tool 



locator first 

; start the mem manager 



_TLStartup 

"MMStartup «0 

Pul lWord ProgID 

_MTStartup ; m i sc tools manager 

"StartUpTool s ProgID; »0; »StartStopRec 

Pul ILong SSRec 

rts 



ShutDown 



: QParms 



"ShutDownTools «0; SSRec 

_MTShutDoiun 

"MMShutDown ProgID 

_TLShutDown 

iGSOS _Quit; :QParms ; 1 

ds 2 

ds 4 



;kill everything we started 



* 
MemRl 



1 oc 



"NewHandl e «63999; ProgID; «attrl_ocked; »0 

Pul ILong BufferHandle 

Deref Buf f erHandl e; BufferPo i nter 

rts 



MakeU i ndow 

"NeuiWindow «U indotuTempl ate 

Pul 1 Long U i ndoiuPtr 

rts 

* 



; grab and save the po i nter 



UakeTextEdit 

"NeuuControl 2 W i ndouuPtr; «0; «TETempl ate 

Pul ILong TEHandle ; save the TextEdit handle 

rts 
* 
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si && 



102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 



: get the event code 

:if nothing, keep looping 

: if w i ndow, close box was cl i eked . 
. . . then we 're done 



EventLoop 

"Tasktlaster »$FFFF; «EventRec 

pi a 

beq EventLoop 

emp «wInGoflway 

bne EventLoop 
rts 
* 

ContentDraui 

"DrawControl s W i ndowPtr 
rtl 

* _ 

Repl yRec 

dw 

dw 

dl 

dw 

adrl F i 1 eName 

dw 

adrl PathName 

F i 1 eName dw 19 

ds 17 

PathName dw 68 

ds 64 



Promptl str 'Choose a file to load:' 

Prompt2 str 'Save file as : ' 

DefaultName dw 10 

strl 'Sample' 

OpenParms dw 12 

OpenRefNum ds 2 ;ref number of newly opened file 

adrl F i 1 eName+2 

dw 



; good or bad? 

;type 

; auxtype 

; type of reference 

;filename reference 

; type of reference 

; pathname reference 



dw 
ds 
ds 
ds 
ds 
ds 
ds 
ds 
OpenEOF ds 




2 
2 
4 
2 
8 
8 
4 
4 



: f i 1 etype 



; 1 ength of newly opened file 



ReadParms dw 4 
ReadRefNum ds 2 
ReadBuffer ds 4 
ReadRequest ds 4 
ReadTransfer ds 4 

CloseParms dw 1 
CloseRefNum ds 2 



SSRec ds 
ProgID ds 



4 
2 



StartStopRec 

dw 
dw $80 



; 640 mode 
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161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 



dw 





adrl 





duj 


17 


duu 


$le,$0100 


duu 


$04, $0300 


diu 


18, $0201 


duu 


$06, $0300 


duu 


27, $0300 


duu 


14, $0300 


duu 


16, $0300 


dm 


15, $0300 


duu 


$lc,$0300 


dw 


20, $0300 


diu 


21, $0101 


duu 


22, $0101 


dm 


5, $0101 


duu 


23, $0101 


duu 


$13, $0200 


dw 


$22, $0100 


dw 


$8, $0101 



BufferHandle ds 4 
Buf f erPo i nter ds 4 
U i ndowPtr ds 4 



EventRec 
eUhat ds 
eMessage ds 
eUhen ds 
eUhere ds 
eflodifiers ds 
TaskData ds 
TaskMask adrl 
adrl 
adrl 
dw 
adrl 
adrl 
adrl 
adrl 

U i ndowTempl ate 
dw 
dw 
adrl 
ds 
dw 
adrl 
dw 
dw 
dw 
dw 
dw 
dw 
dw 
dw 
dw 
dw 



dpage handle 
number of tools 

Resource 
; qu i ckdraw 

qdaux 

event 

font 

w i ndow 

control 

menu 
;1 ist 
; 1 ined 
; d i al og 

scrap 
desk 
;f ile 

print manager 

TextEdit 



2 

4 

4 

4 

2 

4 

$001f5fff 

















: end-W i ndowTempl ate 

SI 100,0000,1 110^1001 

w i ndowt i tl e 

4 

11,0, 199,630 

























; event code 

; event result 

; t i cks since startup 

;global mouse location 

; status of modifier keys 



parm 1 i st 1 ength 

frame bits 

pointer to title 

ref con 

zoomed rectangle 

color table pointer 

vert offset of content 

hor i z offset of content 

data area height 

data area width 

max grow height 

max grow w i dth 

vert, arrow scroll amount 

hor i z arrow scroll amount 

vert, page amount 

hor i z page amount 
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220 




adrl 











; info bar ref con 


221 




dm 











; i nf o bar he i ght 


222 




adrl 











; window procedure 


223 




adrl 











; info bar draw routine 


224 




adrl 


ContentDraui 






; window content draw rtn 


225 




dm 


26,2, 


198,637 




; start i ng pos i t i on rect 


226 




adrl 


-1 








; window plane, -1 is front 


227 




adrl 











; memory for window. 


228 


: end 














229 


U i ndowT 


itle st 


r ' TextEdit 


Example ' 




230 
















231 


TEHandl 


e ds 


4 










232 
















233 


TETempl 


ate 












234 




dm 


18 






number 


of parameters 


235 




adrl 


900 






control 


ID 


236 




dw 


5,5, 170,610 






; boundary rectangle 


237 




adrl 


$85000000 






; ed i tTextControl 


238 




dw 









f 1 ags 




239 




dw 


80111 


_1100_0000_ 


0000 


; more flags 


240 




ds 


4 






ref con 




241 




adrl 


80110 


0010 


1010 ' 


0000 0000 0000 0000_0000 ■ 


242 




dw 


$ffff 


$ffff 


$ffff,$ffff 


; indent rect defs, standards 


243 




dl 


-1 






make a 


default vert scroll bar 


244 




dw 









vert scroll amount - = default 


245 




dl 









start with no hor i z scroll bar 


246 




dm 









horz scrol 1 amount 


247 




dl 









r&f to 


style information 


248 




dw 









textDescr i ptor 


249 




dl 









reference to initial text 


250 




dl 









1 ength 


of initial text 


251 




dl 


65535 




, 


max num of chars allowed 


252 
















253 
254 






























255 




sav 


mwp . 1 
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